home *** CD-ROM | disk | FTP | other *** search
/ Gigarom 1 / Gigarom Macintosh Archives (Quantum Leap)(CDRM1080320)(1993).iso / FILES / DEV / I-Z / Progress Tube Unit.cpt / Progress Tube Unit Folder / Progress Tube Instructions.c next >
Text File  |  1992-12-31  |  4KB  |  106 lines
  1. /*
  2.         <chriskline@aol.com> Dec 31, 1992...
  3.         
  4.         This little unit I hope will help those who want to use progress tubes (the
  5.         familiar "thermometer bar" tubes you see while you're waiting for your
  6.         sub-quadra class mac to do something useful). There are only four functions, 
  7.         which I hope will simplify the use of my routines.
  8.         
  9.         The first thing you need to do is #include "ProgressTube.h" in your source file.
  10.         Then declare a variable of type TubeType in your code. To create a new tube, just
  11.         say:
  12.                 OSErr        didItWork;        // was there enough memory for the new tube? 
  13.                 TubeType    myTube;            // the tube data structure     
  14.                 Str255        myTubeWindowTitle; // the title of the new tube window 
  15.                     
  16.                 didItWork    =    NewTube( &myTube, myTubeWindowTitle );
  17.                     
  18.                 if ( didItWork <> noErr )
  19.                 {
  20.                     fill it, do other processing etc in here...
  21.                 }
  22.         
  23.         Note: you can pass an actual string of characters 
  24.         (i.e.; "\pThis is my tube window title...") in place of the myTubeWindowTitle
  25.         Str255, as long as it's a Pascal-style string (i.e.; prefixed with a length byte,
  26.         or a "\p" in Think C). You can also pass NULL as the title string, in which case
  27.         NewTube() will use the constant kDefaultTubeTitle defined in the header file. You
  28.         may make the default title whatever you want, but it is initially set to an empty
  29.         string (no title).
  30.         
  31.         Note: the tube created will be in a window of the Movable-modal dialog appearance.
  32.         This is so that even though it's not really modal, it looks cool. You can change 
  33.         the window definition procedure by changing the constant kDefaultTubeType defined
  34.         in the header file. (it is initially set to 5, the movableModal definition)
  35.          
  36.         Note: if you want to have the progress tube centered on the main screen, call the
  37.         function:
  38.                  CenterTube ( myTube )
  39.                  
  40.             otherwise it will appear in the position defined by the variable defaultRect,
  41.             which I have initially set to be correct for centering on a 9" screen.
  42.             
  43.         
  44.         Now for the good stuff. To fill the tube, just call the function:
  45.         
  46.                 float        thePercentageToFill; // percentage to fill, as a decimal 
  47.                 
  48.                 FillTube( myTube, myMessageString, &thePercentageToFill);        
  49.                 
  50.         myMessageString is the message to be displayed just above the fill tube, and will
  51.         be displayed in the font and size defined in the header file under the constants
  52.         kDefaultFontNum    and kDefaultFontSize. You can also pass NULL as the message string, 
  53.         in which case FillTube() will use the constant kDefaultTubeMessage defined in the 
  54.         header file. You may make the default message whatever you want, but it is 
  55.         initially set to "\pPlease wait..."
  56.  
  57.         thePercentageToFill is the percentage to fill the tube, as a decimal. For example,
  58.         if your process was half finished, you would say:
  59.                     
  60.                 float     thePercentageToFill
  61.                     
  62.                 thePercentageToFill    =    .50;
  63.                     
  64.                 FillTube( myTube, "\pHalf done! Be patient...", &thePercentageToFill);        
  65.  
  66.         for example, if you were loading in a file, you could set thePercentageToFill equal
  67.         to the total number of bytes already read divided by the total number of bytes in
  68.         the file, and call FillTube() every time you read in more of the file.
  69.         
  70.         Note: it is very important to send in a VARIABLE of type float, because the 
  71.         function expects a pointer to a floating point number, and if you send in 
  72.         something like : 
  73.             FillTube( myTube, "\pHalf done! Be patient...", 50/100 );
  74.         the function will puke and crash.
  75.         
  76.         
  77.         
  78.         Finally, to dispose of a tube, just send it into the function 
  79.                 DisposeTube ( myTube );
  80.                 
  81.             and that's it! It will deallocate the window memory for you.
  82.             
  83.         I hope these functions are useful. I found them to be so, so please let me know
  84.         if you use them, just so I can say, "wow! I've done something useful with my life!"
  85.         
  86.         Oh, BTW, if you are running an event loop in between filling the tube, and you want
  87.         to know if the window that an event occurred in was a tube window, you may know 
  88.         that the NewTube() function sets the refCon field of the tube's windowptr to be
  89.         (long) "TUBE". So you can check if it's a tube by saying
  90.         
  91.                 if ( PointerToTheWindowAnEventOccuredIn->refCon == (long)"TUBE" )
  92.                 {
  93.                     do whatever you want
  94.                 }
  95.                 
  96.                 
  97.             Good luck, and drop me some email at <chriskline@aol.com>
  98.  
  99. */
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.